前置要求
| 要求 | 说明 |
|---|---|
| Node.js | >= 16.10 |
| 推荐编辑器 | VS Code + Vue 官方扩展 |
| 包管理器 | pnpm（推荐）/ npm / yarn |
如果 Node.js 版本低于 16.10，可使用 NVM 切换版本：
nvm install 18
nvm use 18
bash
项目初始化
# 使用 pnpm 初始化 Nuxt 项目
pnpm nuxi init pk-front-nuxt3
cd pk-front-nuxt3
pnpm install
# 启动开发服务器
pnpm dev
bash
启动后访问 http://localhost:3000，看到 "Welcome to Nuxt" 即表示项目创建成功。
Nuxt 工程目录结构
打开 VS Code 查看项目结构，以下是 Nuxt 约定的核心目录：
├── .nuxt/ # 开发过程中自动生成的临时文件
├── .output/ # 构建产物输出目录
├── components/ # 自动导入的 Vue 组件
├── composables/ # 自动导入的组合式函数
├── content/ # Markdown 内容（需安装 @nuxt/content）
├── layouts/ # 布局组件
├── pages/ # 基于文件的路由
├── plugins/ # Nuxt 插件
├── public/ # 静态资源（直接通过 / 访问）
├── server/ # 服务端代码
│ ├── api/ # API 路由
│ ├── routes/ # 服务端路由
│ └── middleware/ # 服务端中间件
├── utils/ # 工具函数（自动导入）
├── app.config.ts # 客户端运行时配置
├── app.vue # 应用入口组件
├── nuxt.config.ts # Nuxt 配置文件
└── error.vue # 全局错误页面
text
关键目录说明
server/ 目录
Nuxt 内置了基于 Nitro 的服务端引擎。在 server/ 目录下创建的文件会自动注册为 API 或路由处理函数：
// server/api/hello.ts
export default defineEventHandler((event) => {
return { message: 'Hello World' }
})
typescript
访问 /api/hello 即可获取响应。此方式无跨域问题（同源请求），且支持更高级的功能如重定向代理。
安全提示：不建议在
server/目录中直接操作数据库。Nuxt 应用可能部署在边缘服务器上，数据库连接信息一旦泄露风险极高。应通过专门的后端服务对接数据库。
app.config.ts
用于定义客户端运行时共享的配置：
export default defineAppConfig({
theme: {
primaryColor: '#007bff',
},
title: 'My Nuxt App',
apiBaseURL: '/api',
})
typescript
集成 @nuxt/content
安装与配置
pnpm add @nuxt/content
bash
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxt/content']
})
typescript
基础使用
创建 content/index.md 文件：
# Hello Nuxt
这是通过 @nuxt/content 渲染的内容。
markdown
在 app.vue 中使用 <ContentDoc> 组件渲染：
<template>
<ContentDoc />
</template>
vue
在 Markdown 中使用 Vue 组件
@nuxt/content 支持 MDC（Markdown Components）语法，允许在 Markdown 文件中混用 Vue 组件。
步骤 1：创建全局内容组件
components/content/Card.vue
text
<template>
<div class="card">
<p>Card Component</p>
<slot />
</div>
</template>
vue
注意：组件必须放在
components/content/子目录中，才能在 Markdown 文件中全局使用。
步骤 2：在 Markdown 中使用
::Card
这里是 Card 的 slot 内容
::
markdown
嵌套使用：
::Card
::Card
嵌套的 Card 内容
::
::
markdown
MDC 语法参考
MDC 是 @nuxt/content 提供的一套在 Markdown 中使用组件的语法规范，支持嵌套、Props 传递等高级用法。详见 content.nuxt.com 的 MDC Syntax 章节。
集成 Pages 文件路由
创建页面
pages/index.vue → /
pages/about.vue → /about
text
<!-- pages/index.vue -->
<template>
<div>
<h1>Hello Nuxt from Page</h1>
<p>Auto Generate Routes</p>
<NuxtLink to="/about">About</NuxtLink>
</div>
</template>
vue
NuxtPage 与 NuxtLink
<!-- app.vue -->
<template>
<div>
<NuxtPage />
</div>
</template>
vue
<NuxtPage>等价于 Vue Router 的<RouterView /><NuxtLink>等价于<RouterLink />，支持to属性进行页面导航
集成 Nuxt DevTools
Nuxt CLI 创建的项目默认已开启 DevTools。检查配置：
// nuxt.config.ts
export default defineNuxtConfig({
devtools: { enabled: true }
})
typescript
在浏览器底部可以看到 Nuxt 图标，点击即可打开 DevTools 面板。
集成 ESLint + Prettier
Prettier 配置
将现有项目中的 .prettierrc 配置文件复制到 Nuxt 项目根目录即可：
{
"semi": false,
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "all"
}
json
重启 VS Code Extension Host 后，底部状态栏出现 Prettier 双勾标记即表示激活成功。
ESLint 配置
1. 安装依赖
pnpm add -D \
eslint \
eslint-plugin-vue \
eslint-parser \
@eslint/eslintrc \
@eslint/js \
@typescript-eslint/parser \
@typescript-eslint/eslint-plugin \
eslint-plugin-nuxt \
vue-eslint-parser \
typescript-eslint
bash
2. 配置 .eslintrc.cjs
module.exports = {
root: true,
env: {
browser: true,
node: true,
es2021: true,
},
parser: 'vue-eslint-parser',
parserOptions: {
parser: '@typescript-eslint/parser',
sourceType: 'module',
},
extends: [
'plugin:vue/vue3-essential',
'eslint:recommended',
'@eslint/eslintrc',
'plugin:@typescript-eslint/recommended',
'plugin:nuxt/recommended',
'prettier', // 放在最后，跳过格式化冲突
],
rules: {
// 自定义规则
},
}
javascript
3. 验证配置
创建一个测试文件验证各规则是否生效：
// server/api/test.ts
// @ts-ignore → TypeScript ESLint 会报错
if (false) {
console.log('hello') // no-constant-condition 会报错
}
typescript
确认错误提示后删除测试文件。
集成要点总结
| 集成项 | 难度 | 关键配置 |
|---|---|---|
| @nuxt/content | 低 | modules 数组中添加 |
| Nuxt DevTools | 极低 | 默认开启 |
| Prettier | 低 | 复制配置文件即可 |
| ESLint | 中 | 需安装多个依赖包并配置 parser |
建议：始终保持 ESLint 配置开启，它能帮助团队编写高质量、风格统一的代码。如果某些规则过于严格，可以针对性调整，但不要全局关闭。
↑